/**
 * File ConversionProgressEvent.java
 * ---------------------------------------------------------
 *
 * Copyright (C) 2012 David Bauske (david.bauske@googlemail.com)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 * - The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 * - The origin of the software must not be misrepresented.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * TL;DR: As long as you clearly give me credit for this Software, you are free to use as you like, even in commercial software, but don't blame me
 * 		if it breaks something.
 */
package net.cl.util.patterns;

/**
 * Contains the data passed with the a conversion event.
 *
 * This class is designed for inheritance, so don't rely on the immutablity of this implementation.
 *
 * @author David Bauske
 */
public class DefaultProgressEvent<SourceType>
{
	protected double		mPercentage;
	protected SourceType	mSourceObject;
	protected String		mStatusMessage	= "";

	/**
	 * Creates a new ConversionProgressEvent
	 *
	 * @param pSource The object that caused the event. Must not be null.
	 * @param pPercentage The current percentage. Must be in the range [0.0 - 1.0].
	 * @throws IllegalArgumentException If the percentage is out of range.
	 * @throws NullPointerException If pSource is null.
	 */
	public <T extends SourceType> DefaultProgressEvent(T pSource, double pPercentage)
	{
		if(pPercentage < 0.0 || pPercentage > 1.0)
		{
			throw new IllegalArgumentException("pPercentage is out of range.");
		}

		if(pSource == null)
		{
			throw new NullPointerException("pSource may not be null.");
		}

		mSourceObject = pSource;
		mPercentage = pPercentage;
	}

	/**
	 * Similar to {@link #DefaultProgressEvent(Object, double)}, exept that the user may provide a detailed status
	 * message.
	 * 
	 * @param pMessage The current status message.
	 */
	public <T extends SourceType> DefaultProgressEvent(T pSource, double pPercentage,
			String pMessage)
	{
		if(pPercentage < 0.0 || pPercentage > 1.0)
		{
			throw new IllegalArgumentException("pPercentage is out of range.");
		}

		if(pSource == null)
		{
			throw new NullPointerException("pSource may not be null.");
		}

		mSourceObject = pSource;
		mPercentage = pPercentage;
		mStatusMessage = pMessage == null ? "" : pMessage; // Ensure, that mStatusMessage doesn't become null.
	}

	/**
	 * @return The current progress of the operation. Lies in the range [0.0 - 1.0]. 0.0 Means <i>no progress
	 *         yet</i>, 1.0 means <i>operation done</i>.
	 */
	public double getPercentage()
	{
		return mPercentage;
	}

	/**
	 * @return The object that caused the event.
	 */
	public SourceType getSource()
	{
		return mSourceObject;
	}

	/**
	 * @return The current status message. Never returns null, returns the empty string id field was not initialized.
	 */
	public String getStatusMessage()
	{
		return mStatusMessage;
	}
}
